Introducing {gs}:
A grammar of recurring calendar events
The Financial Times (FT)
[1] "2020-01-28"
[2] "2020-03-03"
[3] "2020-04-07"
[4] "2020-05-12"
[5] "2020-06-16"
[6] "2020-07-21"
[7] "2020-08-25"
[8] "2020-09-29"
[9] "2020-11-03"
[10] "2020-12-08"
To schedule days in increments from a certain date, we use the on_every_nth() function.
In this case we specify:
35on_fri_thirteenth <-
on_wday("Fri") %>%
only_occur(on_mday(13))
on_fri_thirteenth %>%
schedule_days(from = 2020, to = 2022)[1] "2020-03-13"
[2] "2020-11-13"
[3] "2021-08-13"
[4] "2022-05-13"
Friday the 13th can be thought of as the intersection of:
on_wday() function.on_mday() function.The intersection of these two schedules is found by passing them as arguments to the also_occur() function.
### Assuming a week starts on Monday
in_isoweek_twenty <- in_isoweek(20)
on_mondays <- on_wday("Monday")
in_isoweek_twenty %>%
only_occur(on_mondays) %>%
schedule_days(from = 2020, to = 2025)[1] "2020-05-11"
[2] "2021-05-17"
[3] "2022-05-16"
[4] "2023-05-15"
[5] "2024-05-13"
[6] "2025-05-12"
This schedule can be created as the intersection of two schedules:
on_wday() function.in_isoweek() function.The intersection of these schedules is found using the only_occur() function.
on_mon_wed_fri <- on_wday("Mon", "Wed", "Fri")
on_nth(12,
on_mon_wed_fri,
within_given = "year") %>%
schedule_days(from = 2020, to = 2025)[1] "2020-01-27"
[2] "2021-01-27"
[3] "2022-01-28"
[4] "2023-01-27"
[5] "2024-01-26"
[6] "2025-01-27"
This is a compound schedule with the following parts:
We can create the first schedule using the on_wday() function.
We can then use that schedule object as an argument to the on_nth() function where we also specify that we want the 12th occurrence and that it should be within each given year.
on_fri_sat <- on_wday("Fri", "Sat")
on_nth(-5,
on_fri_sat,
within_given = "month") %>%
schedule_days(during = 2020) [1] "2020-01-17"
[2] "2020-02-15"
[3] "2020-03-14"
[4] "2020-04-11"
[5] "2020-05-16"
[6] "2020-06-13"
[7] "2020-07-17"
[8] "2020-08-15"
[9] "2020-09-12"
[10] "2020-10-17"
[11] "2020-11-14"
[12] "2020-12-12"
Just like the previous example, this can be accomplished as a compound schedule:
on_wday() function.on_nth() function where we also specify -5 as the first argument.The negative integer tells the on_nth() function to look for the last occurrence of the event within the particular period rather than the first.
on_first(on_wday("Sun"), within_given = "month") %>%
roll_forward(to_schedule = on_wday("Sat")) %>%
schedule_days(during = 2020) [1] "2020-01-11"
[2] "2020-02-08"
[3] "2020-03-07"
[4] "2020-04-11"
[5] "2020-05-09"
[6] "2020-06-13"
[7] "2020-07-11"
[8] "2020-08-08"
[9] "2020-09-12"
[10] "2020-10-10"
[11] "2020-11-07"
[12] "2020-12-12"
There are two components to the schedule:
on_wday() and on_first() functions.roll_forward() function.on_fourth_day_month <- on_mday(4)
in_july <- in_month("July")
on_us_independence_day <-
only_occur(on_fourth_day_month,
in_july)
on_us_independence_day %>%
schedule_days(from = 2020, to = 2025)[1] "2020-07-04"
[2] "2021-07-04"
[3] "2022-07-04"
[4] "2023-07-04"
[5] "2024-07-04"
[6] "2025-07-04"
In the United States Independence Day is celebrated on July 4th, regardless of the year.
This can be created as the intersection of two schedules:
in_month() function.on_mday().The intersection of these schedules is found using the only_occur() function.
on_mondays <- on_wday("Mon")
in_jan <- in_month("Jan")
on_mlk_day <-
on_third(on_mondays,
within_given = "month") %>%
only_occur(in_jan)
on_mlk_day %>%
schedule_days(from = 2020, to = 2025)[1] "2020-01-20"
[2] "2021-01-18"
[3] "2022-01-17"
[4] "2023-01-16"
[5] "2024-01-15"
[6] "2025-01-20"
Martin Luther King Jr. Day is a national holiday United States occurring every year on the third Monday in January.
There are three parts to this schedule:
on_wday().in_month()on_third().The schedule of Mondays is passed into the on_third() function as an argument along with the argument specifying it should be within a given month.
You can then get the desired schedule by finding the intersection of the above schedule with the schedule of January days using only_occur().
on_us_federal_holidays <-
on_us_independence_day %>%
also_occur(on_mlk_day)
on_us_federal_holidays %>%
schedule_days(from = 2020, to = 2022)[1] "2020-01-20"
[2] "2020-07-04"
[3] "2021-01-18"
[4] "2021-07-04"
[5] "2022-01-17"
[6] "2022-07-04"
If you want to create a schedule of multiple holidays, you can compose it using individual schedule objects of those holidays.
In this example, we take the schedule objects we have already created for US Independence Day and Martin Luther King Jr. Day and combine them using the also_occur() function.
This can be done any number of times to create a schedule that is arbitrarily complex.